Getting Started¶
This notebook introduces the basics of using xarray_plotly for interactive visualization.
Basic Usage¶
Import the xpx function for full IDE code completion:
In [1]:
Copied!
import numpy as np
import pandas as pd
import xarray as xr
from xarray_plotly import config, xpx
config.notebook() # Configure Plotly for notebook rendering
import numpy as np
import pandas as pd
import xarray as xr
from xarray_plotly import config, xpx
config.notebook() # Configure Plotly for notebook rendering
Create Sample Data¶
Let's create a DataArray with multiple dimensions:
In [2]:
Copied!
# Create sample climate data
np.random.seed(42)
da = xr.DataArray(
np.random.randn(50, 3, 2).cumsum(axis=0), # Random walk
dims=["time", "city", "scenario"],
coords={
"time": pd.date_range("2020-01-01", periods=50, freq="D"),
"city": ["New York", "Los Angeles", "Chicago"],
"scenario": ["baseline", "warming"],
},
name="temperature",
attrs={"long_name": "Temperature Anomaly", "units": "°C"},
)
da
# Create sample climate data
np.random.seed(42)
da = xr.DataArray(
np.random.randn(50, 3, 2).cumsum(axis=0), # Random walk
dims=["time", "city", "scenario"],
coords={
"time": pd.date_range("2020-01-01", periods=50, freq="D"),
"city": ["New York", "Los Angeles", "Chicago"],
"scenario": ["baseline", "warming"],
},
name="temperature",
attrs={"long_name": "Temperature Anomaly", "units": "°C"},
)
da
Out[2]:
<xarray.DataArray 'temperature' (time: 50, city: 3, scenario: 2)> Size: 2kB
array([[[ 0.49671415, -0.1382643 ],
[ 0.64768854, 1.52302986],
[ -0.23415337, -0.23413696]],
[[ 2.07592697, 0.62917043],
[ 0.17821415, 2.0655899 ],
[ -0.69757107, -0.69986671]],
[[ 2.31788924, -1.28410982],
[ -1.54670368, 1.50330237],
[ -1.71040219, -0.38561938]],
[[ 1.40986516, -2.69641352],
[ -0.08105491, 1.27752607],
[ -1.64287398, -1.81036756]],
[[ 0.86548244, -2.58549093],
[ -1.23204849, 1.65322409],
[ -2.24351267, -2.10206131]],
...
[[ 8.05501465, -9.95770321],
[-13.26951282, 1.22160195],
[ -5.39721625, 15.12768686]],
[[ 8.25407435, -10.55792008],
[-13.19971073, 0.83628836],
[ -5.2836989 , 15.78981754]],
[[ 9.84009117, -11.79573558],
[-11.06667736, -1.11579944],
[ -5.435484 , 16.37813474]],
[[ 10.12108303, -12.4184351 ],
[-11.27479961, -1.60880038],
[ -6.02484876, 17.22773684]],
[[ 10.47809852, -13.1113447 ],
[-10.37519973, -1.30150086],
[ -5.21198664, 17.85736568]]])
Coordinates:
* time (time) datetime64[ns] 400B 2020-01-01 2020-01-02 ... 2020-02-19
* city (city) <U11 132B 'New York' 'Los Angeles' 'Chicago'
* scenario (scenario) <U8 64B 'baseline' 'warming'
Attributes:
long_name: Temperature Anomaly
units: °CYour First Plot¶
Create an interactive line plot with a single method call:
In [3]:
Copied!
# Dimensions auto-assign: time→x, city→color, scenario→facet_col
fig = xpx(da).line()
fig
# Dimensions auto-assign: time→x, city→color, scenario→facet_col
fig = xpx(da).line()
fig
The plot is fully interactive:
- Zoom: Click and drag to select a region
- Pan: Hold shift and drag
- Hover: See exact values at each point
- Toggle traces: Click legend items to show/hide
Dimension Assignment¶
Dimensions are assigned to plot "slots" based on their order:
| Dimension | Slot |
|---|---|
| time (1st) | x-axis |
| city (2nd) | color |
| scenario (3rd) | facet_col |
You can override this with explicit assignments:
In [4]:
Copied!
# Put scenario on color, city on facets
fig = xpx(da).line(color="scenario", facet_col="city")
fig
# Put scenario on color, city on facets
fig = xpx(da).line(color="scenario", facet_col="city")
fig
Skipping Slots¶
Use None to skip a slot entirely:
In [5]:
Copied!
# Skip color, so city goes to line_dash instead
fig = xpx(da.sel(scenario="baseline")).line(color=None)
fig
# Skip color, so city goes to line_dash instead
fig = xpx(da.sel(scenario="baseline")).line(color=None)
fig
Customization¶
All methods return a Plotly Figure that you can customize:
In [6]:
Copied!
fig = xpx(da).line()
fig.update_layout(
title="Temperature Anomaly Projections",
template="plotly_white",
legend_title_text="City",
)
fig
fig = xpx(da).line()
fig.update_layout(
title="Temperature Anomaly Projections",
template="plotly_white",
legend_title_text="City",
)
fig
You can also pass Plotly Express arguments directly:
In [7]:
Copied!
fig = xpx(da).line(
title="Temperature Trends",
color_discrete_sequence=["#E63946", "#457B9D", "#2A9D8F"],
template="simple_white",
)
fig
fig = xpx(da).line(
title="Temperature Trends",
color_discrete_sequence=["#E63946", "#457B9D", "#2A9D8F"],
template="simple_white",
)
fig
Configuration¶
Customize label extraction and other behavior with the config module:
In [8]:
Copied!
# View current options
config.get_options()
# View current options
config.get_options()
Out[8]:
{'label_use_long_name': True,
'label_use_standard_name': True,
'label_include_units': True,
'label_unit_format': '[{units}]',
'slot_orders': {'line': ('x',
'color',
'line_dash',
'symbol',
'facet_col',
'facet_row',
'animation_frame'),
'bar': ('x',
'color',
'pattern_shape',
'facet_col',
'facet_row',
'animation_frame'),
'area': ('x',
'color',
'pattern_shape',
'facet_col',
'facet_row',
'animation_frame'),
'scatter': ('x',
'color',
'symbol',
'facet_col',
'facet_row',
'animation_frame'),
'imshow': ('y', 'x', 'facet_col', 'animation_frame'),
'box': ('x', 'color', 'facet_col', 'facet_row', 'animation_frame')}}
Next Steps¶
- Explore different Plot Types
- Learn Advanced Usage patterns
- Check the API Reference